From: Ian Campbell Date: Fri, 27 Nov 2015 12:08:32 +0000 (+0000) Subject: tools/libs/call: Describe return values and error semantics for xencall* X-Git-Tag: archive/raspbian/4.8.0-1+rpi1~1^2~1879 X-Git-Url: https://dgit.raspbian.org/%22http:/www.example.com/cgi/%22https:/%22bookmarks://%22/%22http:/www.example.com/cgi/%22https:/%22bookmarks:/%22?a=commitdiff_plain;h=139ff8ffc94d173531610e093c9a40c4688fa593;p=xen.git tools/libs/call: Describe return values and error semantics for xencall* This behaviour has been confirmed by inspection on: - Linux - NetBSD & FreeBSD (NB: hcall->retval is the hypercall return value only for values >= 0. For negative values the underlying privcmd driver translates the value from Xen to {Net,Free}BSD errno space and returns it as the result of the ioctl, which becomes ret=-1/errno=EFOO in userspace) - MiniOS (which takes care of errno in this library) Signed-off-by: Ian Campbell Acked-by: Wei Liu Acked-by: Ian Jackson Acked-by: Roger Pau Monné Cc: Roger Pau Monné --- diff --git a/tools/libs/call/include/xencall.h b/tools/libs/call/include/xencall.h index 0d91aa8414..3f325f0a5e 100644 --- a/tools/libs/call/include/xencall.h +++ b/tools/libs/call/include/xencall.h @@ -46,6 +46,21 @@ int xencall_close(xencall_handle *xcall); /* * Call hypercalls with varying numbers of arguments. + * + * On success the return value of the hypercall is the return value of + * the xencall function. On error these functions set errno and + * return -1. + * + * The errno values will be either: + * - The Xen hypercall error return (from xen/include/public/errno.h) + * translated into the corresponding local value for that POSIX error. + * - An errno value produced by the OS driver or the library + * implementation. Such values may be defined by POSIX or by the OS. + * + * Note that under some circumstances it will not be possible to tell + * whether an error came from Xen or from the OS/library. + * + * These functions never log. */ int xencall0(xencall_handle *xcall, unsigned int op); int xencall1(xencall_handle *xcall, unsigned int op,